Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

NS_DEV_DOCFOR:objc_class:Menu;,Menu

Inherits From:	Panel : Window : Responder : Object

Declared In:	appkit/Menu.h

Class Description

A Menu is a Panel containing a column of MenuCells in a Matrix.  Each MenuCell can be configured to send its action message to a target, or to bring up a submenu.  When the user clicks a submenu item, the submenu is displayed on the screen, attached to its supermenu so that if the user drags the supermenu, the submenu follows it.  A submenu may also be torn away from its supermenu, in which case it displays a close Button.

Exactly one Menu created by the application is designated as the main Menu for the application (with Applications setMainMenu: method).  This Menu is displayed on top of all other windows whenever the application is active, and should never display a close Button (because it shouldn't have a supermenu).

Many standard Menus are available in Interface Builder, with Menu items that are initialized to work correctly without any additional effort on your part (the Edit, Windows, and Services menus, for example).  You can easily use Interface Builder to create other Menu items that display the commands and perform the actions needed by your application.

See the MenuCell and Matrix class specificiations for more details.  

Instance Variables

id supermenu;

id matrix;

id attachedMenu;

NXPoint lastLocation;

id reserved;

struct _menuFlags {
	unsigned int sizeFitted:1;
	unsigned int 	autoupdate:1;
	unsigned int attached:1;
	unsigned int 	tornOff:1;
	unsigned int wasAttached:1;
	unsigned int wasTornOff:1;
} menuFlags;

supermenu 	The Menu that this Menu is a submenu of.

matrix 	The Matrix that contains the MenuCells.

attachedMenu 	The submenu currently attached to this Menu.  

lastLocation 	Reserved for use by NeXT.

reserved 	Reserved for use by NeXT.

menuFlags.sizeFitted 	True if the Menu has been sized to fit the Matrix.

menuFlags.autoupdate 	True if the Menu accepts automatic update messages.

menuFlags.attached 	True if the Menu is attached to its supermenu.

menuFlags.tornOff 	True if the Menu has been torn off of its supermenu.

menuFlags.wasAttached 	True if the Menu is normally attached to its supermenu.

menuFlags.wasTornOff 	True if the Menu was torn off before tracking a popped-up Menu.

Method Types

Creating a Menu zone	+ setMenuZone:
+ menuZone

Initializing a new Menu	- init
- initTitle:

Setting up the Menu commands	- addItem:action:keyEquivalent:
- setItemList:
- itemList

Finding Menu items	- findCellWithTag:

Building submenus	- setSubmenu:forItem:
- submenuAction:

Managing Menu windows	- moveTopLeftTo::
- windowMoved:
- getLocation:forSubmenu:
- sizeToFit
- close

Displaying the Menu	- display
- setAutoupdate:
- update

Handling events	- mouseDown:
- rightMouseDown:

Archiving	- read:
- write:
- awake

Class Methods

NS_DEV_DOCFOR:objc_method:[Menu-menuZone];,menuZone

+ (NXZone *)menuZone

Returns the zone from which new Menus should be allocated.  If there isn't one, creates and returns a zone named ªMenus.º  After invoking this method, you should allocate all new Menus from this zone.

See also:  - alloc (Object), + setMenuZone:

NS_DEV_DOCFOR:objc_method:[Menu-setMenuZone:];,setMenuZone:

+ setMenuZone:(NXZone *)zone

Sets to zone the zone from which new Menus should be allocated.

See also:  - alloc (Object), + menuZone:

Instance Methods

NS_DEV_DOCFOR:objc_method:[Menu-addItem:action:keyEquivalent:];,addItem:action:keyEquivalent:

- addItem:(const char *)aString
action:(SEL)aSelector
keyEquivalent:(unsigned short)charCode

Adds a new command named aString to the bottom of the receiving Menu and returns the MenuCell created.  The MenuCell's action method is set to aSelector, but its target is nil.  charCode is set as the MenuCell's key equivalent.  The command name and key equivalent aren't checked for duplications within the same Menu (or any other Menu); be sure to assign them uniquely.  The new MenuCell is enabled, but has no tag or alternate title;  your code may set these, but should never set a MenuCell's icon.

This method doesn't automatically redisplay the Menu.  Upon the next display message, the Menu is automatically sized to fit and displayed.

See also:  - setSubmenu:forItem:

NS_DEV_DOCFOR:objc_method:[Menu-awake];,awake

- awake

Checks whether an unarchived Menu should have a close Button.  Your code shouldn't invoke this method; it's invoked by the read: method.  Returns self.

See also:  - read:

NS_DEV_DOCFOR:objc_method:[Menu-close];,close

- close

Overrides Window's close method.  Ensures that attached submenus are closed along with the receiver.

See also:  - close (Window)

NS_DEV_DOCFOR:objc_method:[Menu-display];,display

- display

Overrides Window's display method so that the Menu is automatically sized to fit its Matrix of items if needed.  All Menu methods that change the appearance of the Matrix delay resizing and displaying the Menu until it receives this message.

See also:  - sizeToFit

NS_DEV_DOCFOR:objc_method:[Menu-findCellWithTag:];,findCellWithTag:

- findCellWithTag:(int)aTag

Returns the MenuCell that has aTag as its tag, or nil if no such Cell can be found.  If your application uses MenuCell tages, each MenuCell should have a unique tag.

See also:  - findCellWithTag: (Matrix), - setTag: (ActionCell)

NS_DEV_DOCFOR:objc_method:[Menu-getLocation:forSubmenu:];,getLocation:forSubmenu:

- getLocation:(NXPoint *)theLocation forSubmenu:aSubmenu

Returns the location in screen coordinates at which the lower-left corner of the receiving Menu's submenu should be drawn.  Menu invokes this method whenever it brings up a submenu.  By default, the submenu is to the right of its supermenu, with its title bar aligned with the supermenu's.  Your code need never directly use this method, but may override it to cause the submenu to be attached at a different location.

See also:  - submenuAction:

NS_DEV_DOCFOR:objc_method:[Menu-init];,init

- init

Initializes and returns the receiver, a new instance of Menu, displaying the title ªMenuº.  All other features are as described in the initTitle: method below.

See also:  - initTitle:

NS_DEV_DOCFOR:objc_method:[Menu-initTitle:];,initTitle:

- initTitle:(const char *)aTitle

Initializes and returns the receiver, a new instance of Menu, displaying the title aTitle.  The Menu is positioned in the upper left corner of the screen, and has no command items.  A new Menu must receive an orderFront: message to be displayed on the screen;  the Application object takes care of this for standard Menus.

The Menu is created as a buffered window, of style NX_MENUSTYLE and button mask NX_CLOSEBUTTON (though a Menu hides its close button until it's torn off from its supermenu).  All Menus have an event mask that excludes keyboard events, so they never become the key window or main window.

See also:  - addItem:action:keyEquivalent:, - init

NS_DEV_DOCFOR:objc_method:[Menu-itemList];,itemList

- itemList

Returns the Matrix of MenuCells used by the Menu, which your code can use to add or rearrange command items directly.  Be sure to send sizeToFit after altering the Matrix, as the Menu won't know that the Matrix has been altered.

See also:  - setItemList:, - sizeToFit

NS_DEV_DOCFOR:objc_method:[Menu-mouseDown:];,mouseDown:

- mouseDown:(NXEvent *)theEvent

Overrides the Responder method to catch a mouse-down event instead of passing it along, so that the Menu can track the mouse itself and manage display of its submenus properly.  MenuCell's trackMouse:inRect:ofView: sends this message.  Returns self.

See also:  - rightMouseDown:, - trackMouse:inRect:ofView: (MenuCell)

NS_DEV_DOCFOR:objc_method:[Menu-moveTopLeftTo::];,moveTopLeftTo::

- moveTopLeftTo:(NXCoord)x :(NXCoord)y

Moves the top left corner of the Menu to the position on the screen defined (in screen coordinates) by x and y.  This method is overriden fromWindow's to resize the Matrix if needed before redisplaying the Menu at the new location.

See also:  - moveTo:: (Window)

NS_DEV_DOCFOR:objc_method:[Menu-read:];,read:

- read:(NXTypedStream *)stream

Reads the Menu from the typed stream stream.  Returns self.  

See also:  - awake, - write:

NS_DEV_DOCFOR:objc_method:[Menu-rightMouseDown:];,rightMouseDown:

- rightMouseDown:(NXEvent *)theEvent

Pops the menu up under the cursor position in theEvent.  Before doing so, this method saves the current state of the Menu (including selected cells, attached submenus, menu positions, and so on).  The menu is popped up with no Cells selected or submenus attached.  The Menu is tracked as for a mouseDown: event.  On mouse-up, the Menu's state is restored so that the original Menu arrangment on screen isn't changed.  Returns self.  

See also:  - mouseDown:

NS_DEV_DOCFOR:objc_method:[Menu-setAutoupdate:];,setAutoupdate:

- setAutoupdate:(BOOL)flag

If flag is YES, the Menu will invoke the update action for each MenuCell whenever it receives an update messageÐusually sent by the Application object when autoupdating of windows is enabled.  If NO, the Menu doesn't update its MenuCells on receiving an update message.

See also:  - update, - setAutoupdate: (Application), - setUpdateAction:forMenu: (MenuCell)

NS_DEV_DOCFOR:objc_method:[Menu-setItemList:];,setItemList:

- setItemList:aMatrix

Sets the Menu's Matrix of items to aMatrix.  A following display message will size the Menu to fit the new Matrix before drawing.  Returns the old Matrix.

See also:  - itemList, - display

NS_DEV_DOCFOR:objc_method:[Menu-setSubmenu:forItem:];,setSubmenu:forItem:

- setSubmenu:aMenu forItem:aCell

Sets aMenu as the submenu of the receiver, controlled by the MenuCell aCell.  aCell's target is set to aMenu, its action to submenuAction: and its icon to the arrow indicating that it brings up a submenu.  Doesn't remove aCell's key equivalent.  If aMenu was on screen, it won't be removed from the screen or moved until it's first brought up as a submenu.  Returns aCell.

See also:  - submenuAction:

NS_DEV_DOCFOR:objc_method:[Menu-sizeToFit];,sizeToFit

- sizeToFit

Sizes the Menu's Matrix to its MenuCells, so that all items fit in as small a rectangle as possible, and then fits the Menu to the resized Matrix.  Use this method after you've added or altered items by sending messages directly to the Matrix.  When the Menu is resized, its upper left corner remains fixed.  After performing any necessary resizing, this method redisplays the Menu.

See also:  - sizeToFit (Matrix), - display

NS_DEV_DOCFOR:objc_method:[Menu-submenuAction:];,submenuAction:

- submenuAction:sender

Action method sent to a submenu associated with an entry in a Menu. If sender's Window is a visible Menu, the receiver attaches and displays itself as a submenu of the sender's Menu; otherwise, does nothing.  sender should be the Matrix containing the MenuCell that brings up the submenu.  Returns self.

See also:  - setSubmenu:forItem:

NS_DEV_DOCFOR:objc_method:[Menu-update];,update

- update

Updates the Menu's items.  If the Menu has been set to autoupdate, this method gets the update action method for each of its MenuCells and sends that method to the first of the following that responds to it:  the Menu's delegate, NXApp, or NXApp's delegate.  If a MenuCell's update action returns YES, that MenuCell is redrawn.

See also:  - setAutoupdate: - setUpdateAction:forMenu: (MenuCell)

NS_DEV_DOCFOR:objc_method:[Menu-windowMoved:];,windowMoved:

- windowMoved:(NXEvent *)theEvent

Overrides the Window method to implement tear-off Menu behavior.  When a submenu is torn off, the item selected in its supermenu is unhighlighted.  The submenu is flagged as detached, is moved to the appropriate window level, and displays its close Button.  Returns self.

See also:  - windowMoved: (Window)

NS_DEV_DOCFOR:objc_method:[Menu-write:];,write:

- write:(NXTypedStream *)stream

Writes the receiving Menu to the typed stream stream.  Returns self.

See also:  - read: